Programming the Microsoft Windows Driver Model
Copyright © 1999 by Walter Oney
General Information

The companion disc for Programming the Microsoft Windows Driver Model contains more than 20 sample drivers and test programs to illustrate the topics covered by the book. The file you're viewing contains general information about the disc, as follows:

Directory Structure
Directory of Sample Programs
Using the FastInst Utility
Installing Samples in Windows 98
General Instructions for Building WDM Samples
General Instructions for Building User-Mode Samples
General Instructions for USB Samples
Using WDMWIZ.AWX
WMI Functionality in Windows 98
Definitions of EULA Terms
How to Report Errors

Directory Structure

The SAMPLES directory on the companion disc contains the setup program for the sample programs as well as some common tools used by all the samples. If you elect to install the book samples onto your hard disk, the setup program will copy those common tools too. If you elect not to install the samples onto your hard disk, the setup program will nonetheless install some of the common tools because you won’t otherwise be able to run the samples.

For those book chapters that have sample programs, the companion disc contains a directory for that chapter. The chapter contains subdirectories for each sample program. In many cases, there’s a further subdivision into a SYS directory (containing the WDM driver) and a TEST subdirectory (containing a simple test program for exercising the driver). For example, Chapter 3 has two samples: FILEIO and SEHTEST. The disc therefore has the following directory structure:

Each sample also has an HTML file that describes the overall purpose of the sample and contains brief instructions about how to build and test the sample. Once you’ve installed a particular sample driver, you can easily read this HTML file by clicking on the "More Info" button in the "Sample Information" page of the Device Manager’s property page for the sample device.

Directory of Sample Programs

Using the FastInst Utility

Alternatively, open the INF file of interest in Windows Explorer (double-click on the file icon, or right-click and select Open from the context menu). The WDMBOOK setup program has installed FastInst as the open method for INF files, and you’ll end up invoking FastInst without the hassle of typing.

FastInst will install the driver files for the first device mentioned in the model section for the first manufacturer named in the [manufacturer] section. If you want to override this selection for an INF file that describes multiple devices, specify the device identifier for the device you want:

FastInst presents a progress dialog to reassure you that something is happening. The bar is driven simply off a timer and doesn't reflect the actual progress of the install. You may see the progress bar fill and start over again a number of times the first you run FastInst in a session. Be patient—the installation process can be slow even with FastInst in the picture!

Installing Samples in Windows 98

Since you can’t use FastInst in Windows 98, you must use the regular Add New Hardware wizard. While there may be variations for certain sample programs, here’s a general description of the process:

1. Launch the Add New Hardware wizard from Control Panel. Press the Next button twice to dismiss the first two pages.
2. If you see a dialog listing Plug and Play devices that aren’t working correctly, select the choice that reads, "No, the device isn't in the list" and press the Next button.
3. If you see a dialog asking your permission to search for hardware that isn’t Plug and Play compatible, select the choice that reads, "No, I want to select the hardware from a list" and press the Next button.
4. You’ll now see a dialog that asks you to "Select the type of hardware you want to install." Select the "WDM Book Samples" choice and press the Next button.
5. You’ll now see a dialog that lists all the sample devices you’ve previously installed. If you’re installing a sample for the first time, press the "Have Disk" button. In the ensuing dialog, enter the directory where the sample’s INF file is located. This directory is generally the SYS subdirectory for the sample, but it might be the sample directory itself. The HTM file for the sample will indicate where the appropriate INF is.
6. After selecting the appropriate INF directory, the device will be listed in the Models list box. There will only be one choice, since none of the sample INF files specifies more than one sample device. Select this choice and press Next.
7. In the final dialog, press the Finish button. The wizard will now copy files to perform the installation.

General Instructions for Building WDM Samples

Directory changes: From time to time, Microsoft changes the directory organization for the DDK. If you've installed a version of the DDK later than the RC-1 copy I was using, your builds may fail because of unfindable files. If this happens to you, take a quick look at the errata page on my web site. You can also edit the DSP files as text files and make appropriate changes.

Where files end up: The drivers built by the sample projects end up in the OBJCHK\I386 or OBJFRE\I386 subdirectories. This is the same place that BUILD would put them.

To build a driver using BUILD, open either the checked or free build environment using the shortcut created when you installed the Windows 2000 DDK. Change to the project directory and issue the command "build -cewz". If a directory doesn't contain a SOURCES file, it means that you can't build the corresponding project using BUILD. For example, BUILD can't cope with a few of my samples that require different compile options for different files or that generate a VxD. Additionally, we didn't attempt to make BUILD work for the user-mode test programs because we figured that even die-hard BUILD users were prepared to use the Visual C++ integrated development environment for them.

The SETUP program for the companion disc should have initialized these environment variables on which the build process depends:

• DDKPATH is the name of the base directory for the Windows 2000 Device Driver Kit.
• WDMBOOK is the name of the base directory where the book samples are stored.
• SIWPATH is the pathname of the directory where you’ve installed the Soft-Ice/W debugger from Numega Technologies. If you don’t have a copy of Soft-Ice/W, SIWPATH points to the WDMBOOK directory (where there's a dummy .BAT file) so that the build procedure will operate correctly.
• 98DDK is the pathname of the directory where you’ve installed the Windows 98 Device Driver Kit (if you have). The Win98 DDK is only needed to build the VxD portion of certain sample drivers. If you do all your testing in Windows 2000, you’ll never need to use the Win98 DDK.

The build scripts for these samples will copy the finished driver to the Drivers directory and create a symbol file (with an extension of .NMS) for use by the Numega Soft-Ice/W debugger. The next time you reboot the computer, you will be running the newly built driver. None of my samples has a name that duplicates that of a standard driver file, but you should check for conflicts with other drivers you may have installed.

In Windows 2000, use the FastInst utility to install a sample driver for the first time. The fastest way to install a newer version of a driver is to Disable and re-Enable the device in the Device Manager. The Disable step unloads the current version. The Enable step loads the driver present in the Drivers directory, which by now will the one you’ve just rebuilt.

In Windows 98, you need to use the Add New Hardware wizard to install a sample driver for the first time. The fastest way to replace a driver is to use the Update Driver button from Device Manager.

If you use two computers, be sure that GENERIC.SYS is in the Drivers directory on the computer where you run the sample drivers you build. The setup program for the samples will put it in the Drivers directory on the computer where you install the samples, so you can just copy it.

General Instructions for Building User-Mode Samples

Many of the sample drivers include one or more user-mode components, such as test programs. Each such component has a project file (with a file extension of DSP) for use with Microsoft Visual C++ 6.0. If you want to build one of these components, open the project and use the Build menu command.

General Instructions for USB Samples

You can test the USB sample drivers (Chap11 directory) if you have an Anchor Chips EZUSB development board (see http://www.anchorchips.com). Each of these samples has an EZUSB subdirectory containing the firmware for the "device" that the driver works with. A pre-built firmware image with a file extension of .HEX is there.

To install and test a USB sample driver, start with the Anchor development board in its default state. If you’re not sure of the state, press the Reset button, or unplug and replug the USB connector. Start the EzMr.EXE utility that comes with the Anchor kit. Use the Download button to download the .HEX firmware file to the device. This step will change the personality of the board to match the device that the sample driver expects. The PnP Manager will then detect the new device and ask you to point to the INF file for the driver. The INF file for a USB sample is always named DEVICE.INF and is in the SYS subdirectory for the sample.

Using WDMWIZ.AWX

Appendix C contains detailed instructions about how to use WDMWIZ.AWX, which is the same custom application wizard I used with Microsoft Visual C++ 6.0 to build the code samples. I deliberately left out the following additional instructions so it would be easy to change them up until the very last minute.

The Setup program leaves WDMWIZ.AWX in the WDMBOOK directory on your hard disk. You will need to copy this file to the Visual C++ template directory. The name of that directory on my computers is c:\Program Files\Microsoft Visual Studio\Common\MSDev98\Template. It might be different on your computer, depending on how you installed Visual C++. After you copy the file, the Projects tab on the New dialog in Visual Studio will include a choice labelled WDM Driver Wizard.

WDMWIZ is able to set up most of the project options you need for building a driver. The custom wizard support in Visual Studio is still missing a couple of features, though, and you need to modify the project in these minor respects.

1. Close the workspace if it's open. From Explorer, right-click on the .DSP file that WDMWIZ created for you and select the Fix WDM Driver Project command from the resulting context menu. This will run the FixProj utility that Setup installed on your computer in order to change the names of the project configurations and the output directory structure to better match the DDK. You can then reopen the project in Visual Studio. You will receive a warning at this point that the previous default configuration no longer exists. This is normal, and you can ignore the warning.
2. Open the Project/Settings property page. Select the choice "All Configurations" from the "Settings For" list.
3. Tab to the "Browse Info" page and check "Build Browse Info File". I recommend doing this so you can easily locate the declarations of the kernel-mode support functions and structures your driver uses.
4. Tab to the "Post-build step" page and enter these two commands in the "Post-build command(s)" control:
   
   copy $(TargetPath) $(WINDIR)\system32\drivers
   $(SIWPATH)\nmsym -translate:source,package,always $(TargetPath)
   
   The first of these commands copies the finished driver to the Drivers directory so it will be in place the next time you start your system. The second command invokes the Numega symbol utility to build a symbol file for Soft-Ice/W. If you don't own a copy of Soft-Ice/W, you might as well leave this command out of the build script.
5. If you've requested support for IRP_MJ_SYSTEM_CONTROL, your project includes an MOF file. You will need to set the custom build step for the MOF file depending on where you've installed the MOF compiler. For example:
   
   $(DDKPATH)\bin\mofcomp -wmi -b:$(InputName).bmf $(InputPath)
   $(DDKPATH)\bin\wmimofck $(InputName).bmf
   
   The output file from the custom build is $(InputName).bmf, namely, the binary compiled MOF file.

WMI Functionality in Windows 98

You basically can't test Windows Management Instrumentation (WMI) functionality in the original release of Windows 98, but you can do so in Windows 98, Second Edition. My samples depend on WMILIB.LIB, which wasn't shipped with the originally released version of Windows 98. In addition, there is a bug in the user-mode provider module that makes it impossible to perform WMI queries to WDM drivers.

The setup program for Windows 98, Second Edition doesn't install the WBEM core by default. You must install it by hand at some point. To do so:

• Open Add/Remove Programs in the Control Panel, and select the Windows Setup tab.
• Within the Internet Tools category, indicate that you want to install Web-Based Enterprise Mgmt.
• You may need to reboot your computer before WMI will work. The setup program doesn't indicate that you should, but some testers have reported this as a problem.

Definition of EULA Terms

The End User License Agreement (EULA) to which you agreed when you installed the sample programs uses two terms for which this document provides the definition:

The term SAMPLE CODE includes all of the sample programs referred to in the Directory of Sample Programs earlier in this document. The following modules, present on the companion disc, are not SAMPLE CODE and therefore may not be redistributed in any form:

• WDMWIZ.AWX (But any driver you generate by using WDMWIZ shall be considered SAMPLE CODE for purposes of the EULA.)
• FIXPROJ.EXE
• FASTINST.EXE
• DEVTEST.EXE and DEVSIM.VXD
• SAMCLASS.DLL and SAMCLS16.DLL (But any similar DLL that you generate based on my source code for your own devices or classes of devices shall be considered SAMPLE CODE for purposes of the EULA.)

The following items of SAMPLE CODE, and any modules having the same names built, in whole or in part, from SAMPLE CODE, are designated as Non-Redistributable:

• GENERIC.SYS
• POWCPL.DLL
• WDMSTUB.VXD
• AUTOLAUNCH.EXE
• ALNCH98.EXE
• STARTSERVICE.DLL

You may request a separate, royalty-free license to redistribute these modules by writing directly to the author at waltoney@oneysoft.com. Please don't install a file with one of these names on an end-user system except in accordance with such a license, because you'll probably end up breaking drivers from other vendors and diminishing the end user experience of the operating system.

How to Report Errors

There are errors in the book and in the code samples. If I knew what they were, they wouldn't be there. But I know there's a bunch of them lurking about. I maintain an errata page at my own Web site, which you can reach via http://mspress.microsoft.com/mspress/products/2507 or http://www.oneysoft.com. (Both of these URLs will lead to identical content. We believe there's safety in numbers when it comes to URLs that may break without warning, though.) If you discover a mistake, please send me e-mail at waltoney@oneysoft.com. Let me know if you want me to attribute your correction to you when I add it to the list of errors. I'll assume you prefer to remain anonymous unless you specifically ask for attribution.